The X-Philes (2nd Revision)/The X-Philes Number 1 (1995).iso/xphiles/hp48_2/chasm01.sha/chasm.doc

Text File | 1995-03-23 | 11KB | 430 lines

                C H A S M

             Chip 48 v2.25 assembler

         Written by Steve Scherf, [e-mail]

             Copyright (c) 1991 Steve Scherf


This documentation and the accompanying source code may be freely distributed
with the following restrictions:

    - All files must be distributed intact and unaltered. Any fixes or
      patches to any of the files must be distributed as separate
      information, but may be included with the original files.

    - No person other than the author may sell this software or
      distribute it with any product which is not in the public domain
      or is intended for sale.

    - This software is provided as-is, and is not promised to perform
      reliably. The user of this software does so at his own risk.

    - Possession of this software implies knowledge and acceptance of
      these copyright restrictions.


The following is the list of files that are included in this distribution:

    chasm.c
    chasm.doc
    chasm.h
    grammar.y
    lex.c
    link.c
    Makefile
    README
    sample.ch


Chasm v0.1

The purpose of this program is to aid in the creation of programs for
the Chip 48 v2.25 virtual machine, written by Andreas Gustafsson
([e-mail]). This document assumes a fundamental understanding of
Chip 48. For a description of the Chip 48 program, please refer to the
documentation which is available from a variety of ftp sites and mail servers.


HOW TO USE "CHASM":

Usage:    chasm [-a] [-o output_file] input_file

The "input_file" must be a text file consisting of legal "chasm" instructions.
The instructions in this file will be converted to a binary suitable for
execution by the Chip 48 v2.25 virtual machine. The "-a" option causes output
to be in the form of ascii hex characters rather than in an executable binary
format. This is useful for debugging, as it provides a human-readable output
file. The "-o" option forces the output to be placed in the filename specified
by "output_file". If an error occurs during assembly, no output file is
generated.

Files created by "chasm" are:

    c.out - The default name of the executable binary produced by "chasm".
    c.ascii - The default name of the ascii hex file produced by "chasm".
    c.tmp - A temporary file used during assembly.


INSTRUCTION DESCRIPTIONS:

The following text describes the usage and syntax of the "chasm" instruction
set. The descriptions are all in the following format:

MNEMONIC:    what the mnemonic stands for

    syntax rules

    Explanation of the instruction.

In the syntax rules:

"constant" is a value represented by a number, a single-quoted character, or
    a label. Numbers may be hex, decimal or octal. These types are
    specified as they are in the C language; i.e. hex numbers are
    preceded by 0x, octal numbers are preceded by a zero and decimal
    numbers have no preceding characters. Single-quoted characters
    represent the ascii value of that character. Special characters may
    be escaped as in C.

    Examples:

        0xA9    - hex A9 or decimal 169
        075    - octal 75 or decimal 61
        32    - decimal 32
        'c'    - decimal 99

    Special escape characters are:

        '\t'    - tab or decimal
        '\b'    - backspace or decimal
        '\r'    - carriage return or decimal
        '\n'    - newline or decimal
        '\0'    - null or decimal 0
        '\\'    - backslash or decimal

    Any escaped character that is not in the above list is treated as if
    it were not escaped.

    A special form of constant is a string. As in many languages, a string
    is a series of characters preceded and ended by double quotes. The
    special escape characters defined above are also valid within strings.
    Strings may only be used in the data instruction and have the same
    effect as a series of constants.

    Example:

        "abcd"

        is the same as

        'a', 'b', 'c', 'd'

        or

        97, 98, 99, 100

"label" is a word not beginning with a digit and composed of alphanumeric
    characters and/or the underbar ("_") character.

"register" is a "V" followed by a single hex digit. This corresponds to one
    of the 16 virtual machine registers.

"dtimer", "stimer", and "I" correspond to the special predefined variables
    delay_timer, sound_timer, and I respectively. For explanations of
    these variables, see the documentation for Chip 48 v2.25.


In the explanation of the instructions, "arg1", "arg2" and "arg3" refer to the
first, second and third arguments to the instruction respectively.

Instructions that are marked with an asterisk are pseudo-instructions.

ADD:    add

    add constant, register
    add register, register
    add register, I

    Add arg1 and arg2 and put the result in arg2. In the second case
    VF is true if a carry occurred.

AND:    and

    and register, register

    Store the bitwise and of arg1 and arg2 in arg2.  VF may change.

BCD:    binary coded decimal

    bcd register

    Store the three byte binary coded decimal representation of arg1 in
    the memory address pointed to by I. (I ... I+2)

CLD:    clear display

    cld

    Clear the display.

DATA: *    data

    data datalist

    Store a list of one-byte constants in memory, where datalist is a
    list of constants and/or strings separated by commas. Examples:

        data 'a', 'b', 'c'
        data 0xAB, "hello", 56, 0123, xyz

    In the latter example, xyz is a label that must be defined somewhere
    within the program. The data list may span more than one line.

DEF: *    define

    def label, constant

    Assign a value to a label. Example:

        def xyz, 0xFF

DMP:    dump

    dmp register

    Dump registers V0 through arg1 to the memory address pointed to by I.

DSP:    display sprite

    dsp constant, register, register

    Display sprite pointed to by I. The sprite is taken to be arg1 bytes
    long and is displayed at coordinates arg2, arg3. VF is true if a
    collision occurred with another sprite.

INK:    input key

    ink register

    Get keypress and store hex value in arg1. Execution is suspended
    until a key is pressed. The speaker beeps when a key is pressed.

JMP:    jump

    jmp constant

    Cause execution to branch to the instruction at address arg1.

JOF:    jump to offset

    jof constant

    Cause execution to branch to the instruction at address arg1 plus
    the value in V0. This is good for branch tables. Offsets are easy
    to compute since all true instructions are two bytes; pseudo-
    instructions are as follows: "mem" takes exactly as many bytes as
    specified; "data" takes one byte per element in the data list, and
    one byte per character in a string; "def" takes no memory. Keep in
    mind that if an odd number of bytes is specified with "mem" or "data",
    a pad byte may be added before the next instruction to insure that
    it is on an even address boundary.

JSR:    jump to subroutine

    jsr constant

    Cause execution to branch to the instruction at address arg1. Execution
    returns to the branch point when a "ret" instruction is executed.

MEM: *    memory

    mem constant

    Allocate arg1 bytes of memory. Memory is all zeros.

MOV:    move

    mov register, register
    mov constant, register
    mov constant, I
    mov register, {stimer, dtimer, I}
    mov dtimer, register

    Store value of arg1 in arg2. In the first case VF may change.

OR:    or

    or register, register

    Store the bitwise or of arg1 and arg2 in arg2.  VF may change.

RES:    restore

    res register

    Restore registers V0 through arg1 from the memory address pointed to
    by I.

RET:    return

    ret

    Cause execution to branch to the instruction following the last
    "jsr" instruction executed.

RND:    random

    rnd constant, register

    Generate a random number bitwise and arg1. The result is stored
    in arg2.

SAR:    subtract and replace

    sar register, register

    Subtract arg2 from arg1 and put the result in arg2; VF equals
    not borrow.


SEQ:    skip if equal

    seq register, register

    Skip the next instruction if arg1 equals arg2.

SHL:    shift left

    shl register

    Shift arg1 left one bit; VF equals carry.

SHR:    shift right

    shr register

    Shift arg1 right one bit; VF equals carry.

SIP:    skip if pressed

    sip register

    Skip the next instruction if the key represented by the hex value
    arg1 is pressed.

SNE:    skip if not equal

    sne constant, register
    sne register, register

    Skip the next instruction if arg1 does not equal arg2.

SNP:    skip if not pressed

    snp register

    Skip the next instruction if the key represented by the hex value
    arg1 is not pressed.

SSC:    set sprite coordinates

    ssc register

    Store the address of a 5 byte font sprite for the hex character
    arg1.

SUB:    subtract

    sub register, register

    Subtract arg1 from arg2 and put the result in arg2; VF equals
    not borrow.

XOR:    exclusive or

    xor register, register

    Store the bitwise exclusive or of arg1 and arg2 in arg2. VF may change.


NOTES:

1]    Labels may be used before they are defined, as long as they are defined
    somewhere within the file. The only exception is the "mem"
    pseudo-instruction; labels used in this instruction must be defined
    in advance.

2]    In addition to the "def" instruction, a label may be defined by
    putting it on a line by itself followed by a colon. This will
    set the value of the label to the address of the instruction following
    the label definition.

    Example:

        add V0, V1
        xyz:
        mov 0xFF, V3

    In this code fragment, xyz is set to the address of the "mov"
    instruction. This label is suitable for use in a "jmp", "jsr" or
    "jof" instruction.

3]    The maximum size for a constant is 0xFFF. Some instructions require
    a constant to be smaller. The general rule is: addresses must be
    <= 0xFFF, numerical constants must be <= 0xFF, and sprite sizes
    must be <= 0xF. Using a value that is too large will generate an
    assembler error.

4]    Since both data and instructions share common space, care must be
    taken to ensure that program execution does not fall into addresses
    containing data. This will result in program failure unless the data
    resembles legal instructions. Data space is allocated with the "data"
    and "mem" pseudo-instructions.

5]    Instructions must occupy a single line, except for the "data"
    instruction.

6]    Blank lines and white space are ignored.

7]    Instructions, registers, and numerical constants may be specified in
    either upper or lower case.

8]    Comments are delineated by either the ";" or the "/" character.
    Any text after either of these two characters is ignored by the
    assembler until a newline is reached, so comments must appear after
    instructions.


ERROR MESSAGES:

Error messages generated by the assembler are accompanied by an input file
line number indicating which line in the input file had the error.
Below is a list of possible assembler error messages and their meanings.

"label multiply defined" - A label has been defined more than once.

"constant must be forward declared" - A previously undefined label has been
    used in a "mem" instruction.

"illegal variable usage" - A special variable has been used as an argument
    to an instruction that does not allow that variable.

"duplicate label" - More than one "line label" in a row has been defined.

"constant out of range" - A constant on the specified line is larger than 0xFFF.

"Error - program too large for address space" - The binary that would be
    generated from the input file is larger than the maximum legal size.
    The maximum addressible memory location is 0xFFF, but the first 0x200
    bytes of address space are reserved. Thus, the maximum binary size is
    0xDFF bytes.

"Error - undefined labels:" - The list of labels following this message have
    not been defined.

"Error - constant size:" - The list of line numbers following this message
    specifies instructions that have constants that are illegally large.